NAME
/precompiled/gdbm - database interface

DESCRIPTION
This is the an interface to the gdbm library. This module might or might not be available in your Pike depending on weather gdbm was available when Pike was compiled.

A gdbm database has essentially the same functionality as a mapping, except the syntax is different, and it is located on disk, not in memory. Each gdbm database is one file which contains a set of key-value pairs. Both keys and values are strings and all keys are unique.

NAME
create - open database

SYNTAX
int gdbm->create();
or
int gdbm->create(string file);
or
int gdbm->create(string file, string mode);

DESCRIPTION
Without arguments, this function does nothing. With one argument it opens the given file as a gdbm database, if this fails for some reason, an error will be generated. If a second argument is present, it specifies how to open the database using one or more of the follow flags in a string:

r open database for reading
w open database for writing
c create database if it does not exist
t overwrite existing database
f fast mode

The fast mode prevents the database from syncronizing each change in the database immediately. This is dangerous because the database can be left in an unusable state if Pike is terminated abnormally.

The default mode is "rwc".

NOTA BENE
The gdbm manual states that it is important that the database is closed properly. Unfortunately this will not be the case if Pike calls exit() or returns from main(). You should therefore make sure you call close or destruct your gdbm objects when exiting your program. This will probably be done automatically in the future.

NAME
close - close database

SYNTAX
void gdbm->close();

DESCRIPTION
This closes the database.

NAME
store - store a value in the database

SYNTAX
int gdbm->store(string key, string data);

DESCRIPTION
Associate the contents of 'data' with the key 'key'. If the key 'key' already exists in the database the data for that key will be replaced. If it does not exist it will be added. An error will be generated if the database was not open for writing.

NAME
fetch - fetch a value from the databse

SYNTAX
string gdbm->fetch(string key);

DESCRIPTION
Return the data associated with the key 'key' in the database. If there was no such key in the database, zero is returned.

NAME
delete - delete a value from the database

SYNTAX
int gdbm->delete(string key);

DESCRIPTION
Remove a key from the database. Note that no error will be generated if the key does not exist.

NAME
firstkey - get first key in database

SYNTAX
string gdbm->firstkey();

DESCRIPTION
Return the first key in the database, this can be any key in the database.

NAME
nextkey - get next key in database

SYNTAX
string gdbm->nextkey(string key);

DESCRIPTION
This returns the key in database that follows the key 'key' key. This is of course used to iterate over all keys in the database.

EXAMPLE
/* Write the contents of the database */
for(key=gdbm->firstkey(); k; k=gdbm->nextkey(k))
write(k+":"+gdbm->fetch(k)+"\n");

NAME
reorganize - reorganize database

SYNTAX
int gdbm->reorganize();

DESCRIPTION
Deletions and insertions into the database can cause fragmentation which will make the database bigger. This routine reorganizes the contents to get rid of fragmentation. Note however that this function can take a LOT of time to run.

NAME
sync - synchronize database

SYNTAX
void gdbm->sync();

DESCRIPTION
When opening the database with the 'f' flag writings to the database can be cached in memory for a long time. Calling sync will write all such caches to disk and not return until everything is stored on the disk.